<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Integration with client &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Skulpt: Python / JavaScript bridge" href="based-on-skulpt.html" />
    <link rel="prev" title="Overview" href="overview.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="integration-with-client">
<h1>Integration with client<a class="headerlink" href="#integration-with-client" title="Link to this heading">¶</a></h1>
<p>This section gives an overview of the typical usage of the VM, which
is to run a user’s Python program within the web-app.  Much of the
below also applies to running programs in the unit-test framework.</p>
<section id="set-up-phase-building-a-users-python-code">
<h2>Set-up phase (building a user’s Python code)<a class="headerlink" href="#set-up-phase-building-a-users-python-code" title="Link to this heading">¶</a></h2>
<p>The user’s program will have classes including various decorated
methods, for example methods decorated
<code class="docutils literal notranslate"><span class="pre">&#64;pytch.when_green_flag_clicked</span></code>.  [[1]] Such a decorator attaches
an attribute to the function object, marking it as being a handler for
a particular kind of event.  This happens purely within the Python
world.</p>
<p>When the user clicks the green “play” button in the webapp, the user’s
code is imported using one of Skulpt’s entry points —
<code class="docutils literal notranslate"><span class="pre">Sk.importMainWithBody()</span></code>.  This gives us a ‘module’, and we then
process that module in various ways.  This happens in
<code class="docutils literal notranslate"><span class="pre">import_with_auto_configure()</span></code>.  If you strip away the
error-handling and other ancillary work, this process really consists
of two calls: <code class="docutils literal notranslate"><span class="pre">Sk.importMainWithBody()</span></code> and
<code class="docutils literal notranslate"><span class="pre">maybe_auto_configure_project()</span></code>.</p>
<p>(We keep a global reference to the current “live” project, which is an
object within the user’s imported module.  This keeps everything
alive.)</p>
<p>The auto-configure process looks through the module object for
subclasses of <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> or <code class="docutils literal notranslate"><span class="pre">Stage</span></code>.  For each, it creates a
JavaScript object to represent that <code class="docutils literal notranslate"><span class="pre">Actor</span></code>.  The JS constructor of
that JS <code class="docutils literal notranslate"><span class="pre">Actor</span></code> includes a call to a JS method which registers the
event handlers.</p>
<p>[[2]] That method looks through the Python class for functions
(methods), and, if the any of the attributes mentioned at [[1]] above
exist, calls a JS method which adds the Python method to one of
various maps which track which methods of which classes should be
invoked when various events happen.  As an example, green-flag methods
are handled here by adding a handler object to a “green-flag handlers”
array-like object.</p>
<p>Now everything just sits there until an event happens.</p>
</section>
<section id="creating-threads-when-an-events-happens">
<h2>Creating threads when an events happens<a class="headerlink" href="#creating-threads-when-an-events-happens" title="Link to this heading">¶</a></h2>
<p>First some <code class="docutils literal notranslate"><span class="pre">Threads</span></code> are created:</p>
<p>The client (webapp or unit test framework) calls the current live
project’s <code class="docutils literal notranslate"><span class="pre">on_green_flag_clicked()</span></code> method.  The project iterates
over its <code class="docutils literal notranslate"><span class="pre">Actor</span></code> instances, each of which iterates over its
registered green-flag handlers.  All this eventually comes down to a
series of calls to <code class="docutils literal notranslate"><span class="pre">ThreadGroup.create_thread()</span></code>, one per handler
per <code class="docutils literal notranslate"><span class="pre">Sprite</span></code>/<code class="docutils literal notranslate"><span class="pre">Actor</span></code> instance.</p>
<p>The first two arguments to <code class="docutils literal notranslate"><span class="pre">create_thread()</span></code> are the “Python
function” (which is the unbound method found when iterating over the
attributes of a class in [[2]] above) and the “Python argument” which
is the instance of the <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> on which the <code class="docutils literal notranslate"><span class="pre">Thread</span></code> will run.
These are used to create a new <code class="docutils literal notranslate"><span class="pre">Thread</span></code>.  These arguments are
captured [[3]] in a closure stored in the <code class="docutils literal notranslate"><span class="pre">skulpt_susp</span></code> slot of the
new <code class="docutils literal notranslate"><span class="pre">Thread</span></code>.  The JS code in this closure will in due course invoke
the user’s Python code — <code class="docutils literal notranslate"><span class="pre">Sk.misceval.callsimOrSuspend(py_callable,</span>
<span class="pre">py_arg)</span></code>.</p>
<p>So far we’ve only scheduled that <code class="docutils literal notranslate"><span class="pre">Thread</span></code> for running.  No user
Python code has run yet.</p>
</section>
<section id="running-threads">
<h2>Running threads<a class="headerlink" href="#running-threads" title="Link to this heading">¶</a></h2>
<p>Threads are run as follows:</p>
<p>Pytch scheduling is based around “frames” (as in animation or display
frames, not stack frames).  The application (webapp or unit test
framework) repeatedly calls <code class="docutils literal notranslate"><span class="pre">Project.one_frame()</span></code>.  This (as well as
various housekeeping) calls <code class="docutils literal notranslate"><span class="pre">one_frame()</span></code> on each of its
<code class="docutils literal notranslate"><span class="pre">ThreadGroup</span></code> instances, each of which in turn calls <code class="docutils literal notranslate"><span class="pre">one_frame()</span></code>
on each of its <code class="docutils literal notranslate"><span class="pre">Thread</span></code> instances.</p>
<p>We finally reach the point where the user’s Python code runs:
<code class="docutils literal notranslate"><span class="pre">Thread.one_frame()</span></code>.</p>
<p>The nub of this method is a call to <code class="docutils literal notranslate"><span class="pre">this.skulpt_susp.resume()</span></code>.
The first time a new thread runs, this (via the set-up in [[3]] above)
comes down to invoking the unbound Python method with the <code class="docutils literal notranslate"><span class="pre">Sprite</span></code>
instance as argument, which is equivalent to calling that Python
method on that Python <code class="docutils literal notranslate"><span class="pre">Sprite</span></code> instance.  The rest of
<code class="docutils literal notranslate"><span class="pre">one_frame()</span></code> deals with the three different cases that can happen
when running the user’s code.</p>
<dl class="simple">
<dt>User’s code runs to completion</dt><dd><p>In this case, the thread has finished, becomes a zombie, and is
reaped in due course.</p>
</dd>
<dt>User’s code invokes a “syscall”</dt><dd><p>This means our Pytch VM has to do something (e.g., broadcast a
message, start a sound playing).  In this case, we use Skulpt’s
“suspension” mechanism (essentially a continuation) to allow
resumption in a future call to <code class="docutils literal notranslate"><span class="pre">one_frame()</span></code>.</p>
</dd>
<dt>User’s code raises a Python exception</dt><dd><p>In this case, the client is notified of the exception and the thread
put into a state indicating it raised an exception.</p>
</dd>
</dl>
</section>
<section id="summary">
<h2>Summary<a class="headerlink" href="#summary" title="Link to this heading">¶</a></h2>
<p>To boil this down to just the part which get a reference to the Python
callable within the user’s code and the part that invokes that code:</p>
<p><code class="docutils literal notranslate"><span class="pre">Sk.importMainWithBody()</span></code> returns a “module”, which we can look
through for Python callables (in our case, methods of classes of
interest).</p>
<p><code class="docutils literal notranslate"><span class="pre">Sk.misceval.callsimOrSuspend()</span></code> runs those Python callables with
arguments.</p>
</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../developer/development-setup.html">Development setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/design-overview.html">Design overview</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">VM</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Integration with client</a></li>
<li class="toctree-l3"><a class="reference internal" href="based-on-skulpt.html">Skulpt: Python / JavaScript bridge</a></li>
<li class="toctree-l3"><a class="reference internal" href="project.html">Project</a></li>
<li class="toctree-l3"><a class="reference internal" href="actor.html">Actor: Sprite and Stage</a></li>
<li class="toctree-l3"><a class="reference internal" href="actor-registration.html">Actor-class registration</a></li>
<li class="toctree-l3"><a class="reference internal" href="threading-model.html">Threading model</a></li>
<li class="toctree-l3"><a class="reference internal" href="hat-blocks.html">Hat blocks</a></li>
<li class="toctree-l3"><a class="reference internal" href="syscalls.html">Syscalls</a></li>
<li class="toctree-l3"><a class="reference internal" href="skulpt-pytch-environment.html">Skulpt API / Pytch environment</a></li>
<li class="toctree-l3"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l3"><a class="reference internal" href="ide-web-app.html">Web-app</a></li>
<li class="toctree-l3"><a class="reference internal" href="rendering.html">Rendering</a></li>
<li class="toctree-l3"><a class="reference internal" href="hit-detection.html">Collision and click detection</a></li>
<li class="toctree-l3"><a class="reference internal" href="clones.html">Clones</a></li>
<li class="toctree-l3"><a class="reference internal" href="sounds.html">Sounds</a></li>
<li class="toctree-l3"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
<li class="toctree-l3"><a class="reference internal" href="docstrings.html">Docstrings</a></li>
<li class="toctree-l3"><a class="reference internal" href="attribute-watchers.html">Watching object attributes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../webapp/developer/index.html">Webapp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/index.html">Website</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../build-tools/index.html">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>